Updating the documentation

Introduction

The ISSIE documentation is generated by fsdocs from Markdown documents by the GitHub action .github/workflows/docs.yml, which runs build_docs.sh on every push to master. That outputs a static website to the gh-pages branch, and changes to that branch are automatically deployed to the documentation website.

To change the documentation PR the markdown files to ISSIE master, rebuilding will be automatic when the changes are committed to master.

The Markdown source files can be found on the ISSIE repo:

• Documentation Pages: /docs/*.md
• ISSIE Blog Pages: /docs/updates/*.md
• Embedded (PNG) graphics: /docs/img/**/*.md
• In documentation source files the file path separator is always /

How to develop documentation

For developer preview of changes use dotnet fsdocs watch --noapidocs in the repo root directory. The documentation (without API) will be generated and a browser window opened to preview. Changes will get reloaded automatically.

See Issue 532 for more details of why watch does not work with API.

PR to ISSIE master the changed documentation.

Screenshots

The tutorial's screenshots are taken by a script from a running Issie, not captured by hand:

dotnet fsi scripts/doc-shot-projects.fsx     # write the projects they are taken from
npm run app -- -d                            # Issie must be a debug build
node scripts/doc-shots.js                    # list the shots
node scripts/doc-shots.js all                # take them

doc-shot-projects.fsx writes the tutorial's designs as data through the sheet description DSL, so a screenshot can be retaken against a later Issie without anyone redrawing a schematic. doc-shots.js drives the app through the dev harness and captures each picture.

Two things it exists to get right, both of which the old screenshots got wrong:

• Resolution. A screenshot is shown about 800 CSS px wide on the site. Captured from a maximised window at 1700–1900 px, Issie's 11px UI text arrives at under 5px and cannot be read. Each shot is therefore clipped to the part of the window it is about — usually just the drawn circuit — and taken at twice the device density.
• Staleness. A picture drawn by hand goes out of date silently. One written as data can be regenerated, and a design that no longer simulates fails the run instead of being photographed.

Not every picture is scripted yet: the truth-table, Verilog-editor and waveform-viewer shots are still the hand-captured originals. Adding one means adding a row to SHOTS in doc-shots.js.

Gotcha

build_docs.sh refuses to finish if fsdocs produced no output/index.html. That check is there because fsdocs catches its own phase errors and still exits 0, and the deploy step publishes whatever is in output/ — so without it a failed build silently replaced the live site while the workflow stayed green. If the docs job fails at that line, read the fsdocs output above it rather than re-running.

No secret needs managing: .github/workflows/docs.yml authenticates with secrets.GITHUB_TOKEN, which GitHub mints for each run. (An earlier version of this page described a deploy key that had to be regenerated every six months. There is no such key now.)